%-Abstract
%
%   CSPICE_SAELGV calculates the semi-axis vectors of an ellipse generated
%   by two arbitrary three-dimensional vectors.
%
%-Disclaimer
%
%   THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
%   CALIFORNIA  INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
%   GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
%   ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
%   PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED
%   "AS-IS" TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING
%   ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR
%   A PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
%   SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
%   SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
%
%   IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY,
%   OR NASA BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING,
%   BUT NOT LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF
%   ANY KIND, INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY
%   AND LOST PROFITS, REGARDLESS OF WHETHER CALTECH, JPL, OR
%   NASA BE ADVISED, HAVE REASON TO KNOW, OR, IN FACT, SHALL
%   KNOW OF THE POSSIBILITY.
%
%   RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE
%   OF THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO
%   INDEMNIFY CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING
%   FROM THE ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
%
%-I/O
%
%   Given:
%
%      vec1,
%      vec2   the two vectors defining an ellipse (the generating vectors).
%
%             [3,1]   = size(vec1); double = class(vec1)
%             [3,1]   = size(vec2); double = class(vec2)
%
%             The ellipse is the set of points
%
%                center  +  cos(theta) vec1  +  sin(theta) vec2
%
%             where theta ranges over the interval (-pi, pi] and
%             center is an arbitrary point at which the ellipse
%             is centered.  An ellipse's semi-axes are
%             independent of its center, so the vector center
%             shown above is not an input to this routine.
%
%             'vec1' and 'vec2' need not be linearly independent;
%             degenerate input ellipses are allowed.
%
%   the call:
%
%      [ smajor, sminor ] = cspice_saelgv( vec1, vec2 )
%
%   returns:
%
%      smajor   the semi-major axis of the ellipse.
%
%               [3,1]   = size(smajor); double = class(smajor)
%
%      sminor   the semi-minor axis of the ellipse.
%
%               [3,1]   = size(sminor); double = class(sminor)
%
%-Examples
%
%   Any numerical results shown for this example may differ between
%   platforms as the results depend on the SPICE kernels used as input
%   and the machine specific arithmetic implementation.
%
%      %
%      % Define two arbitrary, linearly independent, vectors.
%      %
%      vec1 = [ 1;  1; 1 ];
%      vec2 = [ 1; -1; 1 ];
%
%      %
%      % Calculate the semi-major and semi-minor axes of an
%      % ellipse generated by the two vectors.
%      %
%      [ smajor, sminor] = cspice_saelgv( vec1, vec2 )
%
%   MATLAB outputs:
%
%      smajor =
%
%          1.4142
%         -0.0000
%          1.4142
%
%      sminor =
%
%          0.0000
%          1.4142
%          0.0000
%
%-Particulars
%
%   We note here that two linearly independent but not necessarily
%   orthogonal vectors vec1 and vec2 can define an ellipse
%   centered at the origin:  the ellipse is the set of points in
%   3-space
%
%      center  +  cos(theta) vec1  +  sin(theta) vec2
%
%   where theta is in the interval (-pi, pi] and center is an
%   arbitrary point at which the ellipse is centered.
%
%   This routine finds vectors that constitute semi-axes of an
%   ellipse that is defined, except for the location of its center,
%   by vec1 and vec2.  The semi-major axis is a vector of largest
%   possible magnitude in the set
%
%      cos(theta) vec1  +  sin(theta) vec2
%
%   There are two such vectors; they are additive inverses of each
%   other. The semi-minor axis is an analogous vector of smallest
%   possible magnitude.  The semi-major and semi-minor axes are
%   orthogonal to each other. If smajor and sminor are choices of
%   semi-major and semi-minor axes, then the input ellipse can also
%   be represented as the set of points
%
%      center  +  cos(theta) smajor  +  sin(theta) sminor
%
%   where theta is in the interval (-pi, pi].
%
%   The capability of finding the axes of an ellipse is useful in
%   finding the image of an ellipse under a linear transformation.
%   Finding this image is useful for determining the orthogonal and
%   gnomonic projections of an ellipse, and also for finding the limb
%   and terminator of an ellipsoidal body.
%
%-Required Reading
%
%   For important details concerning this module's function, please refer to
%   the CSPICE routine saelgv_c.
%
%   MICE.REQ
%   ELLIPSES.REQ
%
%-Version
%
%   -Mice Version 1.0.1, 23-MAR-2015, EDW (JPL)
%
%       Edited I/O section to conform to NAIF standard for Mice documentation.
%
%   -Mice Version 1.0.0, 07-MAY-2008, EDW (JPL)
%
%-Index_Entries
%
%   semi-axes of ellipse from generating vectors
%
%-&

function [ smajor, sminor ] = cspice_saelgv( vec1, vec2 )

   switch nargin

      case 2

         vec1   = zzmice_dp(vec1);
         vec2   = zzmice_dp(vec2);

      otherwise

         error ( ['Usage: [ smajor(3), sminor(3) ] = ' ...
                  'cspice_saelgv( vec1(3), vec2(3) )'] )

   end

   %
   % Call the MEX library.
   %
   try
      [ smajor, sminor ] = mice('saelgv_c', vec1, vec2 );
   catch
      rethrow(lasterror)
   end
